/*
 * Filename: ShortStackApi.h
 *
 * Description: This file contains function prototypes for the
 * IzoT ShortStack LonTalk Compact API.
 *
 * Copyright (c) 2002-2015 Echelon Corporation.  All rights reserved.
 *
 * License:
 * Use of the source code contained in this file is subject to the terms
 * of the Echelon Example Software License Agreement which is available at
 * www.echelon.com/license/examplesoftware/.
 */

#ifndef _SHORTSTACK_API_H
#define _SHORTSTACK_API_H

#define SHORTSTACK_API_VERSION_MAJOR    4
#define SHORTSTACK_API_VERSION_MINOR    30

/*
 * *****************************************************************************
 * TITLE: SHORTSTACK API
 * *****************************************************************************
 *
 * Function prototypes for the ShortStack LonTalk Compact API.
 */

/*
 * Note this file is best included through ShortStackDev.h, which is generated by the
 * IzoT Interface Interpreter.
 */
#ifndef _LON_PLATFORM_H
#   error You must include LonPlatform.h first (prefer including ShortStackDev.h)
#endif  /* _LON_PLATFORM_H */

#ifndef DEFINED_SHORTSTACKDEV_H
#   error You must include ShortStackDev.h first
#endif  /*  DEFINED_SHORTSTACKDEV_H */

#include "ShortStackTypes.h"
#include "ldvTypes.h"

/*
 * ******************************************************************************
 * SECTION: API FUNCTIONS
 * ******************************************************************************
 *
 * This section details the ShortStack LonTalk Compact API functions.
 */

/*
 * Function: LonInit
 * Initializes the ShortStack LonTalk Compact API and Micro Server
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * The function returns a <LonApiError> code to indicate
 * success or failure. The function must be called during application
 * initialization, and prior to invoking any other function of the ShortStack
 * LonTalk Compact API.
 * Note that the Micro Server disables all network communication until this
 * function completes successfully.
 */
extern const LonApiError LonInit(LdvCtrl* ctrl);

/*
 * Function: LonReinit
 *
 * Returns:
 * <LonApiError>
 *
 * The function takes no arguments. It is called from within <LonInit>, but
 * can also be called later during the lifetime of the application in order
 * to re-initialize the Micro Server and framework without having to restart
 * the link layer driver.
 * This is sometimes used by advanced applications which implement pseudo-
 * dynamic interfaces.
 */
extern const LonApiError LonReinit(void);

/*
 * Function: LonExit
 * Closes down the serial driver, prepares the application for exiting.
 *
 * Note some platforms do not support application termination.
 */
extern const LonApiError LonExit(void);

/*
 * Function: LonEventHandler
 * Periodic service to the ShortStack LonTalk Compact API.
 *
 * Remarks:
 * This function must be called periodically by the application.  This
 * function processes any messages that have been received from the Micro Server.
 * The application can call this function as part of the idle loop, or from a
 * dedicated timer-based thread or interrupt service routine. All API callback
 * functions occur within this function's context. Note that the application is
 * responsible for correct context management and thread synchronization, as
 * (and if) required by the hosting platform.
 *
 * This function must be called at least once every 10 ms.  Use the following
 * formula to determine the minimum call rate:
 *  rate = MaxPacketRate / (InputBufferCount - 1)
 * where MaxPacketRate is the maximum number of packets per second arriving for
 * the device and InputBufferCount is the number of input buffers defined for
 * the application.
 */
extern void LonEventHandler(void);

/*
 * Function: LonPollNv
 * Polls a bound, polling, input network variable.
 *
 * Parameters:
 * index - local index of the input network variable
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to poll an input network variable. Polling an input network
 * variable causes this device to solicit all devices that have output network
 * variables connected to this input network variable to send their latest value
 * for the corresponding network variable.
 *
 * The function returns LonApiNoError if the message is successfully put in the
 * transmit queue to send. It is accompanied by the <LonNvUpdateCompleted>
 * completion event.
 * Note the successful completion of this function does not indicate the successful
 * arrival of the requested values. The values received in response to this poll
 * are reported by a series of <LonNvUpdateOccurred> callback invocations.
 *
 * LonPollNv operates on bound input network variables that have been declared
 * with the Neuron C *polled* attribute, only. Also, only output network variables
 * that are bound to the input network variable will be received.
 *
 * Note that it is *not* an error to poll an unbound polling input network
 * variable.  If this is done, the application will not receive any
 * LonNvUpdateOccurred() events, but will receive a LonNvUpdateCompleted() event
 * with the 'success' parameter set to TRUE.
 *
 * Do not use the LonPollNv() function with a network variable that is connected
 * using the standard ISI enrollment process. Network variable connections made
 * with the standard ISI enrollment process are based on unbounded groups (group
 * addressing with group size of zero); this addressing mode is not appropriate
 * for use with the LonPollNv() function or any other acknowledged or request/
 * response service. See the User's Guide for more information about the use of
 * those service types with ISI.
 */
extern const LonApiError LonPollNv(const unsigned index);

/*
 * Function: LonPropagateNv
 * Propagates the value of a bound output network variable to the network.
 *
 * Parameters:
 * index - the local index of the network variable
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * This function returns LonApiNoError if the outgoing NV-update message has been
 * buffered by the driver, otherwise, an appropriate error code is returned.
 * See <LonNvUpdateCompleted> for the completion event that accompanies this API.
 */
extern const LonApiError LonPropagateNv(const unsigned index);

/*
 * Function: LonGetDeclaredNvSize
 * Gets the declared size of a network variable.
 *
 * Parameters:
 * index - the local index of the network variable
 *
 * Returns:
 * Declared initial size of the network variable as defined in the Neuron C
 * model file.
 * Zero if the network variable corresponding to index doesn't exist.
 *
 * Note that this function *could* be called from the LonGetCurrentNvSize()
 * callback.
 */
extern const unsigned LonGetDeclaredNvSize(const unsigned index);

/*
 * Function: LonGetNvValue
 * Returns a pointer to the network variable value.
 *
 * Parameters:
 * index - the index of the network variable
 *
 * Returns:
 * Pointer to the network variable value, or NULL if invalid.
 *
 * Remarks:
 * Use this function to obtain a pointer to the network variable value.
 * Typically ShortStack applications use the global variable created by
 * the LonTalk Interface Developer directly when accessing network variable
 * values. This function can be used to obtain a pointer to the network variable
 * value.
 */
extern volatile void* const LonGetNvValue(const unsigned index);

/*
 * Function: LonSendResponse
 * Sends a response.
 *
 * Parameters:
 * correlator - message correlator obtained with <LonMsgArrived>
 * code - response message code
 * pData - pointer to response data, can be NULL iff len is zero
 * length - number of valid response data bytes in pData
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * This function is called to send an explicit message response.  The correlator
 * is passed in to <LonMsgArrived> and must be copied and saved if the response
 * is to be sent after returning from that routine.  A response code should be
 * in the 0x00..0x2f range.
 */
extern const LonApiError LonSendResponse(const LonCorrelator correlator,
        const LonByte code, const LonByte* const pData, const unsigned length);

/*
 * Function: LonGetUniqueId
 * Returns the unique ID (Neuron ID).
 *
 * Parameters:
 * pId   - pointer to the buffer to hold the unique ID
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Use this function to obtain the local Micro Server's unique ID, if available.
 * The information might not be available immediately following a reset, prior to
 * successful completion of the initialization sequence, or following an
 * asynchronous reset of the host processor.
 *
 * See also the <LonGetLastResetNotification> function for alternative access
 * to the same data.
 *
 * The *Unique ID* is also known as the *Neuron ID*, however, *Neuron ID* is a
 * deprecated term.
 *
 * Previously named lonGetNeuronId.
 */
extern const LonApiError LonGetUniqueId(LonUniqueId* const pId);

/*
 * Function: LonGetVersion
 * Provides the link layer protocol version number.
 *
 * Parameters:
 * pVersion - pointer to hold the version number
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * The function provides the link layer protocol version number into the location
 * pointed to by *pVersion*, if available.
 * The information may not be available immediately following a reset, prior
 * to successful completion of the initialization sequence, or following
 * an asynchronous reset of the host processor.
 *
 * See also the <LonGetLastResetNotification> function for alternative access
 * to the same data.
 */
extern const LonApiError LonGetVersion(LonByte* const pVersion);

/*
 * Function: LonSendServicePin
 * Propagates a service pin message.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Use this function to propagate a service pin message to the network.
 * The function will fail if the device is not yet fully initialized.
 */
extern const LonApiError LonSendServicePin(void);

/*
 * Function: LonSendReset
 * Sends a reset message.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Use this function to send a reset message to the Micro Server.
 * The function will fail if the device is not yet fully initialized.
 */
extern const LonApiError LonSendReset(void);

/*
 * Function: LonGetLastResetNotification
 * Returns a pointer to the most recent reset notification, if any.
 *
 * Returns:
 * Pointer to <LonResetNotification>, reporting the most recent reset notification
 * buffered by the API. The returned pointer is NULL if such data is not available.
 *
 * Remarks:
 * The <LonReset> callback occurs when the Micro Server reports a reset, but the
 * <LonResetNotification> data is buffered by the API for future reference.
 * This is used by the API itself, but the application can query this buffer
 * through the <LonGetLastResetNotification> function. This function delivers
 * a superset of the information from the <LonGetUniqueId> and <LonGetVersion>
 * functions.
 */
extern const volatile LonResetNotification* const LonGetLastResetNotification(void);

#if LON_APPLICATION_MESSAGES

/*
 * Function: LonSendMsg
 * Send an explicit (non-NV) message.
 *
 * Parameters:
 * tag - message tag for this message
 * priority - priority attribute of the message
 * serviceType - service type for use with this message
 * authenticated - TRUE to use authenticated service
 * pDestAddr - pointer to destination address
 * code - message code
 * pData - message data, is NULL if length is zero
 * length - number of valid bytes available through pData
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * This function is called to send an explicit message.  For application messages,
 * the message code should be in the range of 0x00..0x2f.  Codes in the 0x30..0x3f
 * range are reserved for protocols such as file transfer.
 *
 * If the tag field specifies one of the bindable messages tags (tag < #
 * bindable message tags), the pDestAddr is ignored (and can be NULL) because the
 * message is sent using implicit addressing.
 *
 * A successful return from this function indicates only that the message has
 * been queued to be sent.  If this function returns success, the ShortStack
 * LonTalk Compact API will call <LonMsgCompleted> with an indication of the
 * transmission success.
 *
 * If the message is a request, <LonResponseArrived> callback handlers are
 * called when corresponding responses arrive.
 *
 * The device must be configured before your application calls this function.
 * If the device is unconfigured, the function will seem to
 * work:  the application will receive a successful completion event (because
 * the API will successfully pass the request to the Micro Server), but there
 * will be no effect, and the application will not receive a callback (if any).
 */
extern const LonApiError LonSendMsg(const unsigned tag, const LonBool priority,
                                    const LonServiceType serviceType,
                                    const LonBool authenticated,
                                    const LonSendAddress* const pDestAddr,
                                    const LonByte code,
                                    const LonByte* const pData, const unsigned length);

#endif    /* LON_APPLICATION_MESSAGES */

/*
 * ******************************************************************************
 * SECTION: EXTENDED OPTIONAL API FUNCTIONS
 * ******************************************************************************
 *
 * This section details extended API functions:  query functions, update
 * functions, and utility functions. These functions are not typically required
 * for a ShortStack application.
 * To enable these functions, specify the LON_NM_QUERY_FUNCTIONS,
 * LON_NM_UPDATE_FUNCTIONS, or LON_UTILITY_FUNCTIONS macro. These functions are
 * disabled by default to allow for a minimum footprint implementation of the
 * API. The definition of these macros is in the LonTalk Interface
 * Developer-generated file ShortStackDev.h.
 */

#if LON_NM_QUERY_FUNCTIONS

/*
 * Function: LonQueryDomainConfig
 * Request a copy of a local domain table record.
 *
 * Parameters:
 * index - index of requested domain table record (0, 1)
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to request a copy of a local domain table record.
 * This is an asynchronous API. This function returns immediately.
 * The domain information will later be delivered to the <LonDomainConfigReceived>
 * callback.
 * This function is part of the optional network management query API
 * (LON_NM_QUERY_FUNCTIONS).
 */
extern const LonApiError LonQueryDomainConfig(const unsigned index);

/*
 * Function: LonQueryNvConfig
 * Request a copy of network variable configuration data.
 *
 * Parameters:
 * index - index of requested NV configuration table entry
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to request a copy of the local Micro Server's
 * network variable configuration data.
 * This is an asynchronous API. This function returns immediately.
 * The configuration data will later be delivered to the <LonNvConfigReceived>
 * callback. This function is part of the optional network management query API
 * (LON_NM_QUERY_FUNCTIONS).
 */
extern const LonApiError LonQueryNvConfig(const unsigned index);

/*
 * Function: LonQueryAliasConfig
 * Request a copy of alias configuration data.
 *
 * Parameters:
 * index - index of requested alias config table entry
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to request a copy of the local Micro Server's
 * alias configuration data.
 * This is an asynchronous API. This function returns immediately.
 * The configuration data will later be delivered to the <LonAliasConfigReceived>
 * callback. This function is part of the optional network management query API
 * (LON_NM_QUERY_FUNCTIONS).
 */
extern const LonApiError LonQueryAliasConfig(const unsigned index);

/*
 * Function: LonQueryAddressConfig
 * Request a copy of address table configuration data.
 *
 * Parameters:
 * index - index of requested address table entry
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to request a copy of the local Micro Server's
 * address table configuration data.
 * This is an asynchronous API. This function returns immediately.
 * The configuration data will later be delivered to the <LonAddressConfigReceived>
 * callback. This function is part of the optional network management query API
 * (LON_NM_QUERY_FUNCTIONS).
 */
extern const LonApiError LonQueryAddressConfig(const unsigned index);

/*
 * Function: LonQueryConfigData
 * Request a copy of local configuration data.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to request a copy of the local Micro Server's
 * configuration data.
 * This is an asynchronous API. This function returns immediately.
 * The configuration data will later be delivered to the <LonConfigDataReceived>
 * callback. This function is part of the optional network management query API
 * (LON_NM_QUERY_FUNCTIONS).
 */
extern const LonApiError LonQueryConfigData(void);

/*
 * Function: LonQueryStatus
 * Request local status and statistics.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to obtain the local status and statistics of the ShortStack
 * device. This is an asynchronous API. This function returns immediately.
 * The data will later be delivered to the <LonStatusReceived> callback.
 * This function is part of the optional network management query API
 * (LON_NM_QUERY_FUNCTIONS).
 */
extern const LonApiError LonQueryStatus(void);

/*
 * Function: LonQueryTransceiverStatus
 * Request local transceiver status information.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to query the local transceiver status for the Micro Server.
 * This is an asynchronous API. This function returns immediately.
 * The transceiver status will later be delivered to the <LonTransceiverStatusReceived>
 * callback.
 * This function is part of the optional network management query API
 * (LON_NM_QUERY_FUNCTIONS).
 *
 * This function works only for a Power Line transceiver. If your application
 * calls this function for any other transceiver type, the function will seem to
 * work, but the corresponding callback handler will declare a failure.
 */
extern const LonApiError LonQueryTransceiverStatus(void);

#endif /* LON_NM_QUERY_FUNCTIONS */

#if LON_NM_UPDATE_FUNCTIONS

/*
 * Function: LonSetNodeMode
 * Sets the ShortStack Micro Server's mode and state.
 *
 * Parameters:
 * mode - mode of the Micro Server, see <LonNodeMode>
 * state - state of the Micro Server, see <LonNodeState>
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Use this function to set the Micro Server's mode, state, or both.
 * If the mode parameter is *LonChangeState*, then the state parameter can be
 * set to either *LonConfigOffLine* or *LonConfigOnLine*.  Otherwise the state
 * parameter should be *LonStateInvalid* (0).  Note that while the <LonNodeState>
 * enumeration is used to report both the state and the mode (see <LonStatus>),
 * it is *not* possible to change both the state and mode (online/offline) at
 * the same time.
 *
 * This function is part of the optional network management update API
 * (LON_NM_UPDATE_FUNCTIONS).

 * You can also use the shorthand functions <LonGoOnline> and <LonGoOffline>.
 *
 * The device must be configured before your application calls this function.
 * If the device is unconfigured, the function will seem to work because the API
 * will successfully pass the request to the Micro Server, but there will be no
 * effect, and the application will not receive a callback (if any).
 */
extern const LonApiError LonSetNodeMode(const LonNodeMode mode, const LonNodeState state);

/*
 * Function: LonGoOnline
 * Puts the local node online.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to put the local Micro Server into online mode.
 * This function is part of the optional network management update API
 * (LON_NM_UPDATE_FUNCTIONS).
 *
 * The device must be configured before your application calls this function.
 * If the device is unconfigured, the function will seem to work because the API
 * will successfully pass the request to the Micro Server, but there will be no
 * effect, and the application will not receive a callback (if any).
 */
#define LonGoOnline()         LonSetNodeMode(LonApplicationOnLine, LonStateInvalid)

/*
 * Function: LonGoOffline
 * Puts the local node offline.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to put the local Micro Server into offline mode.
 * This function is part of the optional network management update API
 * (LON_NM_UPDATE_FUNCTIONS).
 *
 * The device must be configured before your application calls this function.
 * If the device is unconfigured, the function will seem to work because the API
 * will successfully pass the request to the Micro Server, but there will be no
 * effect, and the application will not receive a callback (if any).
 */
#define LonGoOffline()        LonSetNodeMode(LonApplicationOffLine, LonStateInvalid)

/*
 * Function: LonUpdateAddressConfig
 * Updates an address table record on the Micro Server.
 *
 * Parameters:
 * index - address table index to update
 * pAddress - pointer to address table record
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Use this function to write a record to the local address table.
 * This function is part of the optional network management update API
 * (LON_NM_UPDATE_FUNCTIONS).
 */
extern const LonApiError LonUpdateAddressConfig(const unsigned index, const LonAddress* const pAddress);

/*
 * Function: LonUpdateAliasConfig
 * Updates a local alias table record.
 *
 * Parameters:
 * index - index of alias table record to update
 * pAlias - pointer to the alias table record
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * This function writes a record in the local alias table.
 * This function is part of the optional network management update API
 * (LON_NM_UPDATE_FUNCTIONS).
 */
extern const LonApiError LonUpdateAliasConfig(const unsigned index, const LonAliasConfig* const pAlias);

/*
 * Function: LonUpdateConfigData
 * Updates the configuration data on the Micro Server.
 *
 * Parameters:
 * pConfig - pointer to the <LonConfigData> configuration data
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to update the Micro Server's configuration data based on
 * the configuration stored in the <LonConfigData> structure.
 * This function is part of the optional network management update API
 * (LON_NM_UPDATE_FUNCTIONS).
 */
extern const LonApiError LonUpdateConfigData(const LonConfigData* const pConfig);

/*
 * Function:   LonUpdateDomainConfig
 * Updates a domain table record in the Micro Server.
 *
 * Parameters:
 * index - the index of the domain table to update
 * pDomain - pointer to the domain table record
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * This function can be used to update one record of the domain table.
 * This function is part of the optional network management update API
 * (LON_NM_UPDATE_FUNCTIONS).
 */
extern const LonApiError LonUpdateDomainConfig(const unsigned index, const LonDomain* const pDomain);

/*
 * Function: LonUpdateNvConfig
 * Updates a network variable configuration table record in the Micro Server.
 *
 * Parameter:
 * index - index of network variable
 * pNvConfig - network variable configuration
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * This function can be used to update one record of the network variable
 * configuration table.
 * This function is part of the optional network management update API
 * (LON_NM_UPDATE_FUNCTIONS).
 */
extern const LonApiError LonUpdateNvConfig(const unsigned index, const LonNvConfig* const pNvConfig);

/*
 * Function: LonClearStatus
 * Clears the status statistics on the Micro Server.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * This function can be used to clear the Micro Server's status and statistics
 * records.
 * This function is part of the optional network management update API
 * (LON_NM_UPDATE_FUNCTIONS).
 */
extern const LonApiError LonClearStatus(void);

#endif /* LON_NM_UPDATE_FUNCTIONS */

#if LON_UTILITY_FUNCTIONS

/*
 * Function: LonSendPing
 * Sends a ping command to the ShortStack Micro Server.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Use this function to send a ping command to the Micro Server
 * to verify that communications with the Micro Server are functional.
 * The <LonPingReceived> callback handler function processes the reply to the query.
 * This function is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 * For a more comprehensive test facility see <LonRequestEcho>.
 */
extern const LonApiError LonSendPing(void);

/*
 * Function: LonNvIsBound
 * Sends a command to the ShortStack Micro Server to query whether
 * a given network variable is bound.
 *
 * Parameter:
 * index - index of network variable
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Use this function to query whether the given network variable is bound.
 * You can use this function to ensure that transactions are initiated only for
 * connected network variables.  The <LonNvIsBoundReceived> callback handler
 * function processes the reply to the query.
 * This function is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 */
extern const LonApiError LonNvIsBound(const unsigned index);

/*
 * Function: LonMtIsBound
 * Sends a command to the ShortStack Micro Server to query whether
 * a given message tag is bound.
 *
 * Parameter:
 * index - index of network variable
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Use this function to query whether the given message tag is bound or not.
 * You can use this function to ensure that transactions are initiated only for
 * connected message tags.  The <LonMtIsBoundReceived> callback handler function
 * processes the reply to the query.
 * This function is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 */
extern const LonApiError LonMtIsBound(const unsigned index);

/*
 * Function: LonGoUnconfigured
 * Puts the local node into the unconfigured state.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to put the Micro Server into the unconfigured state.
 * This function is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 */
extern const LonApiError LonGoUnconfigured(void);

/*
 * Function: LonGoConfigured
 * Puts the local node into the configured state.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to put the Micro Server in the configured state and online
 * mode.
 * This function is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 */
extern const LonApiError LonGoConfigured(void);

/*
 * Function: LonQueryAppSignature
 * Queries the Micro Server's current version of the host application signature.
 *
 * Parameter:
 * bInvalidate - flag to indicate whether to invalidate the signature
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to query the Micro Server's current version of the host
 * application signature. If the bInvalidate flag is TRUE, the Micro Server
 * invalidates its copy of the signature *AFTER* reporting it to the host.
 * This function is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 */
extern const LonApiError LonQueryAppSignature(LonBool bInvalidate);

/*
 * Function: LonQueryVersion
 * Request version details from the Micro Server
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Call this function to request the Micro Server application and core library
 * version numbers, both delivered as triplets of major version, minor version
 * and build number (one byte each) through the <LonVersionReceived> callback.
 * This function is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 */
extern const LonApiError LonQueryVersion(void);

/*
 * Function: LonRequestEcho
 * Sends arbitrary test data to the Micro Server and requests a modulated echo.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * LonRequestEcho transmits LON_ECHO_SIZE (6) bytes of arbitrary data, chosen by
 * the caller of the function, to the Micro Server. The Micro Server returns these
 * data bytes to the host, but increments each byte by one, using unsigned 8-bit
 * addition without overflow. When the response is received, the API activates the
 * <LonEchoReceived> callback.
 */
extern const LonApiError LonRequestEcho(const LonByte data[LON_ECHO_SIZE]);

/*
 * Function: LonSetPostResetPause
 * Configures the Micro Server's post-reset pause as 0 (zero, disabled) or in
 * the 1..255ms range.
 *
 * Returns:
 * <LonApiError>.
 *
 * Remarks:
 * Starting with release 4.30, the Micro Server enforces a pause immediately
 * after it transmits an uplink reset notification message. This pause is 50ms
 * by default. During this pause, the Micro Server does nothing. This allows
 * the host time to receive and process the reset notification, which may
 * require resetting the host-side link layer driver.
 *
 * This API may be used to disable the post-reset pause (set to zero), or to
 * select a pause duration in the 1..255 ms range. The Micro Server stores the
 * value in on-chip EEPROM memory, so this only needs setting once.
 */
extern const LonApiError LonSetPostResetPause(LonByte duration);

#endif /* LON_UTILITY_FUNCTIONS */

/*
 * ******************************************************************************
 * SECTION: CALLBACK HANDLER PROTOTYPES
 * ******************************************************************************
 *
 * Following are the prototypes for the Shortstack LonTalk Compact host API
 * callback handler functions. Code in ShortStackApi.c can call these functions,
 * which the application must provide and fill with meaningful code. Skeletons
 * for these callback functions are provided in ShortStackHandlers.c.
 */

/*
 * Callback:   LonResetOccurred
 * Occurs when the Micro Server has completed a reset.
 *
 * Parameters:
 * pResetNotification - <LonResetNotification> structure with capabilities and
 * identifying data.
 *
 * Remarks:
 * The pointer to <LonResetNotification> is only valid for the duration of
 * this callback, but the API buffers the notification details. Use the
 * <LonGetLastResetNotification> function to fetch a pointer to that buffer when
 * needed.
 *
 * The reset message contains the link-layer protocol version number implemented
 * by the Micro Server. The application should make sure that it can handle that
 * link-layer protocol by comparing it with the API's link-layer protocol
 * version number defined by LON_LINK_LAYER_PROTOCOL_VERSION.
 */
extern void LonResetOccurred(const LonResetNotification* const pResetNotification);

/*
 * Callback: LonWink
 * Occurs when the Micro Server has received a WINK command.
 */
extern void LonWink(void);

/*
 * Callback: LonOffline
 * Occurs when the Micro Server has received a command to enter the offline state.
 *
 * Remarks:
 * The Micro Server does not actually go offline until the <LonOffline> callback
 * function returns and the ShortStack LonTalk Compact API sends a confirmation
 * message to the Micro Server. Thus, the host application should assume that
 * the Micro Server is offline only after this callback completes processing.
 */
extern void LonOffline(void);

/*
 * Callback: LonOnline
 * Occurs when the Micro Server has received a command to enter the online state.
 *
 * Remarks:
 * The Micro Server does not actually go online until the <LonOnline> callback
 * function returns and the ShortStack LonTalk Compact API sends a confirmation
 * message to the Micro Server. Thus, the host application should assume that
 * the Micro Server is online only after this callback completes processing.
 */
extern void LonOnline(void);

/*
 * Callback: LonServicePinPressed
 * Occurs when the service pin has been activated.
 *
 * The IzoT Interface Interpreter (III) generated framework implements this
 * event handler within the generated code, and dispatches application-specific
 * onService events. See the <LonServicePinEvent> prototype definition below
 * for the type of the onService handler supported by III.
 */
extern void LonServicePinPressed(void);

/*
 * Callback: LonServicePinHeld
 * Occurs when the service pin has been continuously activated for a
 * configurable time.
 *
 * Remarks:
 * Use the LonTalk Interface Developer to enable this feature and to specify the
 * duration for which the service pin must be activated to trigger this callback.
 *
 * The IzoT Interface Interpreter (III) generated framework implements this
 * event handler within the generated code, and dispatches application-specific
 * onService events. See the <LonServicePinEvent> prototype definition below
 * for the type of the onService handler supported by III.
 */
extern void LonServicePinHeld(void);

/*
 * Callback: LonServicePinEvent
 * Occurs when the service pin has been activated or held.
 *
 * The IzoT Interface Interpreter (III) generated framework dispatches
 * application-specific onService events based on this prototype.
 */
extern void LonServicePinEvent(LonBool held);

/*
 * Callback: LonNvUpdateOccurred
 * Occurs when new input network variable data has arrived.
 *
 * Parameters:
 * index - global index (local to the device) of the network variable in question
 * pSourceaddress - pointer to source address description
 *
 * Remarks:
 * The network variable with local index given in this callback has been updated
 * with a new value. The new value is already stored in the network variable's
 * location; access the value through the global variable representing the
 * network variable, or obtain the pointer to the network variable's value from
 * the network variable table. The pSourceAddress pointer is only valid for the
 * duration of this callback.
 *
 * For an element of a network variable array, the index is the global network
 * variable index plus the array-element index. For example, if nviVolt[0] has
 * global network variable index 4, then nviVolt[1] has global network variable
 * index 5.
 *
 * Also, if this is a non-volatile network variable, that is, it has the
 * LON_NVDESC_PERSISTENT_MASK attribute set, store its value in non-volatile
 * memory as implemented by your application. An network variable is a
 * non-volatile network variable if it is declared with an *eeprom* keyword in
 * the model file or if it is a configuration property network variable (CPNV).
 */
extern void LonNvUpdateOccurred(const unsigned index, const LonReceiveAddress* const pSourceAddress);

/*
 * Callback:   LonNvUpdateCompleted
 * Signals completion of a network variable update
 *
 * Parameters:
 * index - global index (local to the device) of the network variable that was
 * processed
 * success - indicates whether the update was successful or unsuccessful
 *
 * Remarks:
 * This callback completes the transaction that was started by calling the
 * <LonPropagateNv> or <LonPollNv> API functions.  The index parameter
 * delivered with this callback matches the one from the API invocation.
 */
extern void LonNvUpdateCompleted(const unsigned index, const LonBool success);

/*
 * Callback: LonGetCurrentNvSize
 * Gets the current size of a network variable.
 *
 * Parameters:
 * index - the local index of the network variable
 *
 * Returns:    Current size of the network variable.
 *             Zero if the network variable corresponding to index doesn't exist.
 *
 * Remarks:
 * If the network variable size is fixed, this function should return
 * <LonGetDeclaredNvSize>. If the network variable size is changeable, the
 * current size should be returned. The default implementation for changeable
 * type network variables returns 0, and must be updated by the application
 * developer.
 *
 * The Micro Server will not propagate a network variable with size 0, nor will
 * it generate an update event if a network variable update is received from the
 * network when the current network variable size is 0.
 *
 * Note that even though this is a callback function, it *is* legal for the
 * application to call <LonGetDeclaredNvSize> from this callback.
 */
extern const unsigned LonGetCurrentNvSize(const unsigned index);

/*
 * Callback: LonNvdDeserializeNvs
 * Initializes the network variable values from non-volatile storage.
 *
 * Remarks:
 * This callback is called by the API's initialization routine <LonInit>.
 * If the device contains any network variable that requires persistent storage,
 * such as an eeprom network variable or a configuration property network variable
 * (CPNV), the application should provide a mechanism to store and retrieve its
 * data from persistent memory.
 *
 * See <LonNvdSerializeNvs> for the complimentary API.
 */
extern const LonApiError LonNvdDeserializeNvs(void);

/*
 * Callback: LonNvdSerializeNvs
 * Updates the persistent network variable values in non-volatile storage.
 *
 * Remarks:
 * This callback is called by the API whenever the device receives a new value
 * for a persistent network variable from the network. The event is not fired
 * when your application makes local assignments, such as assignments to
 * properties flagged with the device_specific and manufacture attributes.
 *
 * If the device contains any network variable that requires persistent storage,
 * such as an eeprom network variable or a configuration property network variable
 * (CPNV), the application should provide a mechanism to store and retrieve its
 * data from persistent memory.
 *
 * See <LonNvdDeserializeNvs> for the complimentary API.
 */
extern const LonApiError LonNvdSerializeNvs(void);

#if LON_APPLICATION_MESSAGES

/*
 * Callback: LonMsgArrived
 * Occurs when an application message arrives.
 *
 * Parameters:
 * pAddress - source and destination address (see <LonReceiveAddress>)
 * correlator - correlator; preserve and use with <LonSendResponse>
 * priority - indicates whether its a priority message
 * serviceType - indicates the service type of the message
 * authenticated - TRUE if the message was (successfully) authenticated
 * code - message code
 * pData - pointer to message data bytes, might be NULL if dataLength is zero
 * dataLength - length of bytes pointed to by pData
 *
 * Remarks:
 * This callback reports the arrival of a message that is neither a network
 * variable message, nor a non-Nv message that is otherwise processed by the
 * Micro Server. Typically, this callback handler function is used with
 * application message codes in the value range indicated by the
 * <LonApplicationMessageCode> enumeration.
 * All pointers are only valid for the duration of this callback.
 */
extern void LonMsgArrived(const LonReceiveAddress* const pAddress,
                          const LonCorrelator correlator,
                          const LonBool priority,
                          const LonServiceType serviceType,
                          const LonBool authenticated,
                          const LonByte code,
                          const LonByte* const pData, const unsigned dataLength);
/*
 * Callback: LonResponseArrived
 * Occurs when a response arrived.
 *
 * Parameters:
 * pAddress - source and destination address used for response (see <LonResponseAddress>)
 * tag - tag to match the response to the request
 * code - response code
 * pData - pointer to response data, might by NULL if dataLength is zero
 * dataLength = number of bytes available through pData.
 *
 * Remarks:
 * This callback occurs when a message arrives in response to an earlier request,
 * sent with the <LonSendMsg> API.
 */
extern void LonResponseArrived(const LonResponseAddress* const pAddress,
                               const unsigned tag,
                               const LonByte code,
                               const LonByte* const pData, const unsigned dataLength);

/*
 * Callback: LonMsgCompleted
 * Occurs when a message transaction has completed.  See <LonSendMsg>.
 *
 * Parameters:
 * tag - use to correlate the event with the message sent
 * success - TRUE for successful completion, otherwise FALSE
 *
 * Remarks:
 * For unacknowledged or repeated messages, the transaction is complete when
 * the message has been sent with the configured number of retries. For
 * acknowledged messages, the Micro Server calls <LonMsgCompleted> with *success*
 * set to TRUE after receiving acknowledgments from all of the destination
 * devices, and calls <LonMsgCompleted> with *success* set to FALSE if
 * the transaction timeout period expires before receiving acknowledgements
 * from all destinations.  Likewise, for request messages, the transaction is
 * considered successful when the Micro Server receives a response from each of the
 * destination devices, and unsuccessful if the transaction timeout expires
 * before responses have been received from all destinations devices.
 */
extern void LonMsgCompleted(const unsigned tag, const LonBool success);

#endif    /* LON_APPLICATION_MESSAGES    */

#if LON_NM_QUERY_FUNCTIONS

/*
 * Callback: LonDomainConfigReceived
 * Callback following call to <LonQueryDomainConfig>.
 *
 * Parameters:
 * pDomain - pointer to the <LonDomain> structure iff success is TRUE
 * success - boolean success indicator
 *
 * Remarks:
 * The pDomain pointer to the <LonDomain> structure is only valid for the
 * duration of this callback, and only if the success parameter indicates
 * success. Applications that need to preserve this information beyond the
 * duration of this callback must make a copy of the <LonDomain> data.
 * This callback is part of the optional network management query API
 * (LON_NM_QUERY_FUNCTIONS).
 */
extern void LonDomainConfigReceived(const LonDomain* const pDomain, const LonBool success);

/*
 * Callback: LonNvConfigReceived
 * Callback following call to <LonQueryNvConfig>.
 *
 * Parameters:
 * pNvConfig - pointer to the <LonNvConfig> structure iff successful
 * success - boolean success indicator
 *
 * Remarks:
 * The pNvconfig pointer is only valid for the duration of this callback, and
 * only if the success parameter is true. Applications that need to preserve this
 * information beyond the duration of this callback must make a copy of the
 * <LonNvConfig> data. This callback is part of the optional
 * network management query API (LON_NM_QUERY_FUNCTIONS).
 */
extern void LonNvConfigReceived(const LonNvConfig* const pNvConfig, const LonBool success);

/*
 * Callback: LonAliasConfigReceived
 * Callback following call to <LonQueryAliasConfig>.
 *
 * Parameters:
 * pAliasConfig - pointer to the <LonAliasConfig> structure iff successful
 * success - boolean success indicator
 *
 * Remarks:
 * The pAliasConfig pointer is only valid for the duration of this callback, and
 * only if the success parameter is true. Applications that need to preserve this
 * information beyond the duration of this callback must make a copy of the
 * <LonAliasConfig> data.
 * This callback is part of the optional network management query API
 * (LON_NM_QUERY_FUNCTIONS).
 */
extern void LonAliasConfigReceived(const LonAliasConfig* const pAliasConfig, const LonBool success);

/*
 * Callback:   LonAddressConfigReceived
 * Callback following call to <LonQueryAddressConfig>.
 *
 * Parameters:
 * pAddress - pointer to the <LonAddress> structure iff successful
 * success - boolean success indicator
 *
 * Remarks:
 * The pAddress pointer is only valid for the duration of this callback, and
 * only if the success parameter is true. Applications that need to preserve this
 * information beyond the duration of this callback must make a copy of the
 * <LonAddress> data. This callback is part of the optional network management
 * query API (LON_NM_QUERY_FUNCTIONS).
 */
extern void LonAddressConfigReceived(const LonAddress* const pAddress, const LonBool success);

/*
 * Callback: LonConfigDataReceived
 * Callback following call to <LonQueryConfigData>.
 *
 * Parameters:
 * pConfigData - pointer to the <LonConfigData> structure iff successful
 * success - boolean success indicator
 *
 * Remarks:
 * The pConfigData pointer is only valid for the duration of this callback,
 * and only if the success parameter is true. Applications that need to preserve
 * this information beyond the duration of this callback must make a copy of
 * the <LonConfigData> data.
 * This callback is part of the optional network management query API
 * (LON_NM_QUERY_FUNCTIONS).
 */
extern void LonConfigDataReceived(const LonConfigData* const pConfigData, const LonBool success);

/*
 * Callback: LonStatusReceived
 * Callback following call to <LonQueryStatus>.
 *
 * Parameters:
 * pStatus - pointer to the <LonStatus> structure iff successful.
 * success - boolean success indicator
 *
 * Remarks:
 * The pStatus pointer is only valid for the duration of this callback, and only
 * if the success parameter is true. Applications that need to preserve this
 * information beyond the duration of this callback must make a copy of the
 * <LonStatus> data. This callback is part of the optional network management
 * query API (LON_NM_QUERY_FUNCTIONS).
 */
extern void LonStatusReceived(const LonStatus* const pStatus, const LonBool success);

/*
 * Callback: LonTransceiverStatusReceived
 * Callback following a call to <LonQueryTransceiverStatus>.
 *
 * Parameters:
 * pStatus - pointer to the <LonTransceiverParameters> structure iff successful
 * success - boolean success indicator
 *
 * Remarks:
 * The pStatus pointer is only valid for the duration of this callback, and
 * only if the success parameter is true. Applications that need to preserve this
 * information beyond the duration of this callback must make a copy of the
 * <LonTransceiverParameters> data. This callback is part of the optional
 * network management query API (LON_NM_QUERY_FUNCTIONS).
 *
 * The function <LonQueryTransceiverStatus> only works for a Power Line
 * transceiver. If your application invokes that function for any other
 * transceiver type, this callback will declare a failure through the second
 * parameter.
 */
extern void LonTransceiverStatusReceived(const LonTransceiverParameters* const pStatus, const LonBool success);
#endif  /* LON_NM_QUERY_FUNCTIONS */

#if LON_DMF_ENABLED
/*
 * Callback: LonMemoryRead
 * Read memory in the ShortStack device's memory space.
 *
 * Parameters:
 * address - virtual address of the memory to be read
 * size - number of bytes to read
 * pData - pointer to a buffer to store the requested data
 *
 * Remarks:
 * The ShortStack event handler calls <LonMemoryRead> whenever it receives a
 * network management memory read request that fits into the registered file
 * access window. This callback function is used to read data starting at the
 * specified virtual Smart Transceiver memory. This applies to template files,
 * configuration property value files, user-defined files, and possibly to other
 * data. The address space for this command is limited to the Smart
 * Transceiver's 64 KB address space.
 */
extern const LonApiError LonMemoryRead(const unsigned address,
                                       const unsigned size,
                                       void* const pData);

/*
 * Callback: LonMemoryWrite
 * Update memory in the ShortStack device's memory space.
 *
 * Parameters:
 * address - virtual address of the memory to be update
 * size - number of bytes to write
 * pData - pointer to the data to write
 *
 * Remarks:
 * The ShortStack event handler calls <LonMemoryWrite> whenever it receives a
 * network management memory write request that fits into the registered file
 * access window. This callback function is used to write data at the specified
 * virtual Smart Transceiver memory.  This applies to configuration property
 * value files, user-defined files, and possibly to other data. The address space
 * for this command is limited to the Smart Transceiver's 64 KB address space.
 */
extern const LonApiError LonMemoryWrite(const unsigned address,
                                        const unsigned size,
                                        const void* const pData);
#endif  /* LON_DMF_ENABLED */

#if LON_UTILITY_FUNCTIONS
/*
 * Callback: LonPingReceived
 * The ShortStack Micro Server has sent a ping command.
 *
 * Remarks:
 * The ShortStack Micro Server has sent a ping command. This command can be
 * a response to the ping command sent by the host application
 * to the Micro Server. This callback is part of the optional
 * utility API (LON_UTILITY_FUNCTIONS).
 */
extern void LonPingReceived(void);

/*
 * Callback: LonNvIsBoundReceived
 * Callback following a call to <LonNvIsBound>.
 *
 * Parameters:
 * index - index of the network variable
 * bound - indicates whether the network variable is bound
 *
 * Remarks:
 * The Micro Server has responded to the <LonNvIsBound> request. The boolean
 * variable *bound* tells whether the network variable identified by index
 * is bound. This callback is part of the optional
 * utility API (LON_UTILITY_FUNCTIONS).
 */
extern void LonNvIsBoundReceived(const unsigned index, const LonBool bound);

/*
 * Callback: LonMtIsBoundReceived
 * Callback following a call to <LonMtIsBound>.
 *
 * Parameters:
 * index - index of the message tag
 * bound - indicates whether the message tag is bound
 *
 * Remarks:
 * The Micro Server has responded to the <LonMtIsBound> request. The boolean
 * variable *bound* tells whether the message tag identified by index
 * is bound. This callback is part of the optional
 * utility API (LON_UTILITY_FUNCTIONS).
 */
extern void LonMtIsBoundReceived(const unsigned index, const LonBool bound);

/*
 * Callback: LonGoUnconfiguredReceived
 * Callback following a call to <LonGoUnconfigured>.
 *
 * Remarks:
 * The Micro Server has responded to the <LonGoUnconfigured> request.
 * If the Micro Server was in a configured state before the <LonGoUnconfigured>
 * request was sent, it will reset after going to the unconfigured state.
 * This callback is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 */
extern void LonGoUnconfiguredReceived(void);

/*
 * Callback: LonGoConfiguredReceived
 * Callback following a call to <LonGoConfigured>.
 *
 * Remarks:
 * The Micro Server has responded to the <LonGoConfigured> request.
 * The Micro Server will not reset after going into the configured state unless
 * some serious error, such as an application checksum error, is detected in the
 * process.
 * This callback is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 */
extern void LonGoConfiguredReceived(void);

/*
 * Callback: LonAppSignatureReceived
 * Callback following a call to <LonQueryAppSignature>.
 *
 * Parameter:
 * appSignature - Micro Server's copy of the host's application signature
 *
 * Remarks:
 * The Micro Server has responded to the <LonQueryAppSignature> request.
 * If the *bInvalidate* flag was set to TRUE in the <LonQueryAppSignature>
 * request, the Micro Server has already invalidated the signature by the time
 * this callback is called.
 * This callback is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 */
extern void LonAppSignatureReceived(LonWord appSignature);

/*
 * Callback: LonVersionReceived
 * Callback following a call to <LonQueryVersion>.
 *
 * Parameters:
 * appMajor - the major version number for the Micro Server application, 0..255
 * appMinor - the minor version number for the Micro Server application, 0..255
 * appBuild - the build number for the Micro Server application, 0..255
 * coreMajor - the major version number for the Micro Server core library, 0..255
 * coreMinor - the minor version number for the Micro Server core library, 0..255
 * coreBuild - the build number for the Micro Server core library, 0..255
 *
 * Remarks:
 * The Micro Server has responded to a <LonQueryVersion> request.
 * This callback is part of the optional utility API (LON_UTILITY_FUNCTIONS).
*/
extern void LonVersionReceived(unsigned appMajor, unsigned appMinor, unsigned appBuild,
                               unsigned coreMajor, unsigned coreMinor, unsigned coreBuild);

/*
 * Callback: LonEchoReceived
 * Callback following a call to <LonRequestEcho>.
 *
 * Parameters:
 * LON_ECHO_SIZE payload bytes, as sent through <LonRequestEcho>, but modified by the
 * Micro Server by adding one to each byte, using an unsigned 8-bit addition without
 * overflow detection.
 *
 * Remarks:
 * The Micro Server has responded to a <LonRequestEcho> request. The host application
 * should now confirm that the echoed data matches the expectations; mismatching data
 * can indicate an incorrect host application or link layer driver, or permanent or
 * transient link layer errors. These link layer errors could, for example, be
 * introduced by incorrect line termination, excessive coupling or cross-talk, or by
 * excessive or out-of-sync link layer bit rates.
 * This callback is part of the optional utility API (LON_UTILITY_FUNCTIONS).
 */
extern void LonEchoReceived(const LonByte data[LON_ECHO_SIZE]);
#endif  /* LON_UTILITY_FUNCTIONS */

/*
 * Callback: LonCustomCommunicationParameters
 * Callback to enforce application-specific communication parameters.
 *
 * Parameters:
 * params: A pointer to 16 communication parameter bytes
 *
 * Result:
 * A boolean flag, indicating whether custom communication parameters have been
 * set.
 *
 * Remarks:
 * WARNING! Use the <LonCustomCommunicationParameters> API with caution, as the
 * specification of incorrect communication parameters may prevent further
 * communication with the Micro Server over the link layer and/or the network,
 * and may render the Micro Server permanently defunct.
 *
 * By default, IzoT ShortStack uses the default communication parameters and
 * clocking preferences which are programmed into the Micro Server.
 * For example, the SS430_FT6050_SYS20000kHz standard Micro Server is
 * configured for a TP/FT-10 transceiver attached to an FT 6050 chip configured
 * for 20MHz system clock, while the SS430_PL3170_PL20C_SYS10000kHz Micro
 * Server is configured for a PL-20C transceiver attached to a PL 3170 chip
 * configured for a 10MHz clock.
 *
 * We recommend that you use the Micro Server's default communication
 * parameters and clock settings where possible.
 *
 * You could use the <LonCustomCommunicationParameters> callback, for example,
 * to configure the same Micro Server for power line communications in a
 * CENELEC member state or affiliate using the PL-20C transceiver type, and
 * for communication in countries not governed by CENELEC using the PL-20N
 * transceiver type. You application could, for example, select the
 * communication parameter record suitable for the device's shipping
 * destination based on a jumper setting.
 *
 * To use this feature, write the desired 16 communication parameter bytes
 * and return a logical true value to activate them.
 *
 * PL 3120, PL 3170 and PL 3150 based Smart Transceivers, operating on an
 * external 10MHz crystal, may be configured for the following C-band power
 * line channels:
 *
 * Transceiver PL-20C, algorithm 1, clock 10MHz * 1/2 / 1.000000 at OSC1
 * Communication Parameters   0x05.5E.00.3F.A6.77.67.00.08.4A.00.00.10.00.00.00
 *
 * Transceiver PL-20C-LOW, algorithm 1, clock 10MHz * 1/2 / 1.000000 at OSC1
 * Communication Parameters   0x05.5E.00.3F.A6.77.67.00.08.4A.00.00.12.00.00.00
 *
 * Transceiver PL-20N, algorithm 1, clock 10MHz * 1/2 / 1.000000 at OSC1
 * Communication Parameters   0x05.5E.00.3F.A6.77.67.00.08.0E.01.00.10.00.00.00
 *
 * Transceiver PL-20N-LOW, algorithm 1, clock 10MHz * 1/2 / 1.000000 at OSC1
 * Communication Parameters   0x05.5E.00.3F.A6.77.67.00.08.0E.01.00.12.00.00.00
 */
extern LonBool LonCustomCommunicationParameters(LonByte* const pParameters);

#ifdef LON_NVDESC_ENCRYPT_MASK
/*
 * Callback: LonEncrypt
 * Callback to engage the application-specific encryption algorithm.
 *
 * Parameters:
 * index - the global index of the related network variable, or -1 if none
 * inSize - the number of bytes that are to be encrypted
 * inData - pointer to first byte that is to be encrypted
 * outSize - output parameter, points to variable holding size of encrypted data in bytes
 * outData - output parameter, points to pointer to encrypted data
 *
 * Remarks:
 * The function encrypts <inSize> bytes, starting at <inData>, and writes the result
 * into a buffer allocated by the function itself. The buffer must remain valid after
 * returning from <LonEncrypt>, but may be re-used with the next call to a <LonEncrypt>
 * or <LonDecipher> function. If successful, the output parameters <outSize> and
 * <outData> provide access to this buffer. The function is required to provide its
 * own buffer; in-situ encryption, overwriting <inData>, is not permitted.
 * The function returns results through the standard <LonApiError> enumeration.
 * The algorithm used with <LonEncrypt> must be reversible through <LonDecipher>.
 * */
extern LonApiError LonEncrypt(int index,
                              unsigned inSize, const void* inData,
                              unsigned* const outSize, void** outData);

/*
 * Callback: LonDecipher
 * Callback to engage the application-specific decryption algorithm.
 *
 * Parameters:
 * index - the global index of the related network variable, or -1 if none
 * inSize - the number of bytes that are to be decrypted
 * inData - pointer to first byte that is to be decrypted
 * outSize - output parameter, points to variable holding size of decrypted data in bytes
 * outData - output parameter, points to pointer to decrypted data
 *
 * Remarks:
 * The function decrypts <inSize> bytes, starting at <inData>, and writes the result
 * into a buffer allocated by the function itself. The buffer must remain valid after
 * returning from LonDecipher(), but may be re-used with the next call to a <LonEncrypt>
 * or <LonDecipher> function. If successful, the output parameters <outSize> and
 * <outData> provide access to this buffer. The function is required to provide its
 * own buffer; in-situ encryption, overwriting <inData>, is not permitted.
 * The function returns results through the standard <LonApiError> enumeration.
 * The algorithm used with <LonDecipher> must be reversible through <LonEncrypt>.
 * */
extern LonApiError LonDecipher(int index,
                               unsigned inSize, const void* inData,
                               unsigned* const outSize, void** outData);
#endif  /* LON_NVDESC_ENCRYPT_MASK */

/*
 * Function: LonResume
 * Resumes a suspended link layer driver.
 *
 * Remarks:
 * The LonResume function requests that a suspended link layer driver resume normal
 * operation.
 * Use <LonSuspend> to suspend the link layer driver.
 *
 * Note that the suspend and resume functionality are optional driver features not
 * supported by all implementations. Implementations which do not support this API
 * are expected to return LonApiNotSupported.
 */
extern const LonApiError LonResume();

/*
 * Function: LonSuspend
 * Suspends a link layer driver.
 *
 * Parameters:
 * mode - implementation-specific suspend mode flags
 *
 * Remarks:
 * The LonSuspend() function passes the suspend request to the driver's optional
 * LdvSuspend() API, using suspend mode flags defined by this driver implementation.
 * See LDV_SUSPEND_* flags defined in <ldv.h> for suspend options supported by
 * the current driver.
 * Use <LonResume>() to resume normal operation.
 */
extern const LonApiError LonSuspend(unsigned mode, unsigned timeout);

#endif /* _SHORTSTACK_API_H */
